home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1995 February: Tool Chest / Dev.CD Feb 95 / Dev.CD Feb 95.toast / Tool Chest / QuickDraw GX / QuickDraw GX Info / QuickDraw GX Interfaces / Interfaces & Libraries / interfaces / Collections.h < prev    next >
Encoding:
C/C++ Source or Header  |  1994-03-24  |  11.1 KB  |  426 lines  |  [TEXT/MPS ]
  1. /* ------------------------------------------------------------------------------
  2.  
  3.     FILENAME
  4.         Collections.h
  5.  
  6.     DESCRIPTION
  7.         This file contains all of the public data structures, constants, and 
  8.         function declarations for the Collection Manager.
  9.  
  10.     COPYRIGHT
  11.         Copyright © Apple Computer, Inc. 1989, 1990, 1991, 1992, 1993
  12.         All rights reserved. 
  13.  
  14. ------------------------------------------------------------------------------- */
  15.  
  16.  
  17. #ifndef __COLLECTIONMANAGER__
  18. #define __COLLECTIONMANAGER__
  19.  
  20. #ifndef __TYPES__
  21. #include <Types.h>
  22. #endif
  23.  
  24.  
  25. /*************/
  26. /* Constants */
  27. /*************/
  28.  
  29.  
  30. /* Collection Manager Gestalt Selector... */
  31.  
  32. enum {
  33.     gestaltCollectionMgrVersion = 'cltn'
  34. };
  35.  
  36.  
  37. /* Collection Manager Error Result Codes... */
  38.  
  39. enum {
  40.     collectionItemLockedErr = -5750,
  41.     collectionItemNotFoundErr = -5751,
  42.     collectionIndexRangeErr = -5752,
  43.     collectionVersionErr = -5753
  44. };
  45.  
  46.  
  47. /* Convenience constants for functions which optionally return values... */
  48.  
  49. enum {
  50.     dontWantTag                = 0L,
  51.     dontWantId                = 0L,
  52.     dontWantSize            = 0L,
  53.     dontWantAttributes    = 0L,
  54.     dontWantIndex            = 0L,
  55.     dontWantData            = 0L
  56. };
  57.  
  58.  
  59. /* attributes bits */
  60.  
  61.  
  62. enum {
  63.     noCollectionAttributes = 0x00000000,        /* no attributes bits set */
  64.     allCollectionAttributes = 0xFFFFFFFF,        /* all attributes bits set */
  65.     userCollectionAttributes = 0x0000FFFF,        /* user attributes bits */
  66.     defaultCollectionAttributes = 0x40000000    /* default attributes - unlocked, persistent */
  67. };
  68.  
  69.  
  70. /* 
  71.     Attribute bits 0 through 15 (entire low word) are reserved for use by the application.
  72.     Attribute bits 16 through 31 (entire high word) are reserved for use by the Collection Manager.
  73.     Only bits 31 (collectionLockBit) and 30 (collectionPersistenceBit) currently have meaning.
  74. */
  75.  
  76.  
  77. enum {
  78.     collectionUser0Bit            = 0,
  79.     collectionUser1Bit            = 1,
  80.     collectionUser2Bit            = 2,
  81.     collectionUser3Bit            = 3,
  82.     collectionUser4Bit            = 4,
  83.     collectionUser5Bit            = 5,
  84.     collectionUser6Bit            = 6,
  85.     collectionUser7Bit            = 7,
  86.     collectionUser8Bit            = 8,
  87.     collectionUser9Bit            = 9,
  88.     collectionUser10Bit            = 10,
  89.     collectionUser11Bit            = 11,
  90.     collectionUser12Bit            = 12,
  91.     collectionUser13Bit            = 13,
  92.     collectionUser14Bit            = 14,
  93.     collectionUser15Bit            = 15,
  94.     
  95.     collectionReserved0Bit        = 16,
  96.     collectionReserved1Bit        = 17,
  97.     collectionReserved2Bit        = 18,
  98.     collectionReserved3Bit        = 19,
  99.     collectionReserved4Bit        = 20,
  100.     collectionReserved5Bit        = 21,
  101.     collectionReserved6Bit        = 22,
  102.     collectionReserved7Bit        = 23,
  103.     collectionReserved8Bit        = 24,
  104.     collectionReserved9Bit        = 25,
  105.     collectionReserved10Bit        = 26,
  106.     collectionReserved11Bit        = 27,
  107.     collectionReserved12Bit        = 28,
  108.     collectionReserved13Bit        = 29,
  109.     
  110.     collectionPersistenceBit    = 30,
  111.     collectionLockBit                = 31
  112. };
  113.         
  114.         
  115. /* attribute masks */
  116.  
  117.  
  118. enum {
  119.     collectionUser0Mask            = 1L << collectionUser0Bit,
  120.     collectionUser1Mask            = 1L << collectionUser1Bit,
  121.     collectionUser2Mask            = 1L << collectionUser2Bit,
  122.     collectionUser3Mask            = 1L << collectionUser3Bit,
  123.     collectionUser4Mask            = 1L << collectionUser4Bit,
  124.     collectionUser5Mask            = 1L << collectionUser5Bit,
  125.     collectionUser6Mask            = 1L << collectionUser6Bit,
  126.     collectionUser7Mask            = 1L << collectionUser7Bit,
  127.     collectionUser8Mask            = 1L << collectionUser8Bit,
  128.     collectionUser9Mask            = 1L << collectionUser9Bit,
  129.     collectionUser10Mask            = 1L << collectionUser10Bit,
  130.     collectionUser11Mask            = 1L << collectionUser11Bit,
  131.     collectionUser12Mask            = 1L << collectionUser12Bit,
  132.     collectionUser13Mask            = 1L << collectionUser13Bit,
  133.     collectionUser14Mask            = 1L << collectionUser14Bit,
  134.     collectionUser15Mask            = 1L << collectionUser15Bit,
  135.  
  136.     collectionReserved0Mask        = 1L << collectionReserved0Bit,
  137.     collectionReserved1Mask        = 1L << collectionReserved1Bit,
  138.     collectionReserved2Mask        = 1L << collectionReserved2Bit,
  139.     collectionReserved3Mask        = 1L << collectionReserved3Bit,
  140.     collectionReserved4Mask        = 1L << collectionReserved4Bit,
  141.     collectionReserved5Mask        = 1L << collectionReserved5Bit,
  142.     collectionReserved6Mask        = 1L << collectionReserved6Bit,
  143.     collectionReserved7Mask        = 1L << collectionReserved7Bit,
  144.     collectionReserved8Mask        = 1L << collectionReserved8Bit,
  145.     collectionReserved9Mask        = 1L << collectionReserved9Bit,
  146.     collectionReserved10Mask    = 1L << collectionReserved10Bit,
  147.     collectionReserved11Mask    = 1L << collectionReserved11Bit,
  148.     collectionReserved12Mask    = 1L << collectionReserved12Bit,
  149.     collectionReserved13Mask    = 1L << collectionReserved13Bit,
  150.  
  151.     collectionPersistenceMask    = 1L << collectionPersistenceBit,
  152.     collectionLockMask            = 1L << collectionLockBit
  153. };
  154.  
  155.  
  156.  
  157. /* the Collection Manager trap */
  158.  
  159.  
  160. #define collectionManagerTrap 0xABF6    /* C++ will choke on an enum in a trap definition */
  161.  
  162.  
  163. /***********/
  164. /* Types   */
  165. /***********/
  166.  
  167.  
  168. typedef struct PrivateCollectionRecord *Collection;        /* abstract data type for a collection */
  169.  
  170. typedef long CollectionTag;                                        /* collection member 4 byte tag */
  171.  
  172. #pragma procname CollectionFlatten
  173. typedef pascal OSErr (*CollectionFlattenProcPtr)( long size, void *data, void *refCon );
  174. typedef CollectionFlattenProcPtr CollectionFlattenProc;
  175.  
  176. #pragma procname CollectionException
  177. typedef pascal OSErr (*CollectionExceptionProcPtr)( Collection c, OSErr status );
  178. typedef CollectionExceptionProcPtr CollectionExceptionProc;
  179.  
  180.  
  181. /**********************************************************************
  182.  ***************            Public Interfaces            ***********************
  183.  *********************************************************************/
  184.  
  185.  
  186. #ifdef __cplusplus
  187. extern "C" {
  188. #endif
  189.  
  190.  
  191. pascal Collection NewCollection (void)
  192. = {0x7000,collectionManagerTrap};
  193.  
  194.  
  195. pascal void DisposeCollection (Collection)
  196. = {0x7001,collectionManagerTrap};
  197.  
  198.  
  199. pascal Collection CloneCollection (Collection)
  200. = {0x7002,collectionManagerTrap};
  201.  
  202.  
  203. pascal long CountCollectionOwners (Collection)
  204. = {0x7003,collectionManagerTrap};
  205.  
  206.  
  207. pascal Collection CopyCollection (Collection srcCollection, Collection dstCollection)
  208. = {0x7004,collectionManagerTrap};
  209.  
  210.  
  211. pascal long GetCollectionDefaultAttributes (Collection)
  212. = {0x7005,collectionManagerTrap};
  213.  
  214.  
  215. pascal void SetCollectionDefaultAttributes (Collection,
  216.                                                            long whichAttributes,
  217.                                                             long newAttributes)
  218. = {0x7006,collectionManagerTrap};
  219.  
  220.  
  221. pascal long CountCollectionItems (Collection)
  222. = {0x7007,collectionManagerTrap};
  223.  
  224.  
  225. pascal OSErr AddCollectionItem (Collection,
  226.                                              CollectionTag,
  227.                                           long id,
  228.                                           long itemSize,
  229.                                           void *itemData)
  230. = {0x7008,collectionManagerTrap};
  231.  
  232.  
  233. pascal OSErr GetCollectionItem (Collection,
  234.                                            CollectionTag,
  235.                                           long id,
  236.                                           long *itemSize,
  237.                                           void *itemData)
  238. = {0x7009,collectionManagerTrap};
  239.  
  240.  
  241. pascal OSErr RemoveCollectionItem (Collection, CollectionTag, long id)
  242. = {0x700A,collectionManagerTrap};
  243.  
  244.  
  245. pascal OSErr SetCollectionItemInfo (Collection,
  246.                                                    CollectionTag,
  247.                                                     long id,
  248.                                                     long whichAttributes,
  249.                                                   long newAttributes)
  250. = {0x700B,collectionManagerTrap};
  251.  
  252.  
  253. pascal OSErr GetCollectionItemInfo (Collection,
  254.                                                    CollectionTag,
  255.                                                     long id,
  256.                                                   long *index,
  257.                                                   long *itemSize,
  258.                                                     long *attributes)
  259. = {0x700C,collectionManagerTrap};
  260.  
  261.  
  262. pascal OSErr ReplaceIndexedCollectionItem (Collection,
  263.                                                                long index,
  264.                                                             long itemSize,
  265.                                                            void *itemData)
  266. = {0x700D,collectionManagerTrap};
  267.  
  268.  
  269. pascal OSErr GetIndexedCollectionItem (Collection,
  270.                                                           long index,
  271.                                                       long *itemSize,
  272.                                                      void *itemData)
  273. = {0x700E,collectionManagerTrap};
  274.  
  275.  
  276.  
  277. pascal OSErr RemoveIndexedCollectionItem (Collection, long index)
  278. = {0x700F,collectionManagerTrap};
  279.  
  280.  
  281. pascal OSErr SetIndexedCollectionItemInfo (Collection,
  282.                                                            long index,
  283.                                                           long whichAttributes,
  284.                                                            long newAttributes)
  285. = {0x7010,collectionManagerTrap};
  286.  
  287.  
  288. pascal OSErr GetIndexedCollectionItemInfo (Collection,
  289.                                                                long index,
  290.                                                            CollectionTag *,
  291.                                                         long *id,
  292.                                                          long *itemSize,
  293.                                                         long *attributes)
  294. = {0x7011,collectionManagerTrap};
  295.  
  296.  
  297. pascal Boolean CollectionTagExists (Collection, CollectionTag)
  298. = {0x7012,collectionManagerTrap};
  299.  
  300.  
  301. pascal long CountCollectionTags (Collection)
  302. = {0x7013,collectionManagerTrap};
  303.  
  304.  
  305. pascal OSErr GetIndexedCollectionTag (Collection,
  306.                                                   long whichTag,
  307.                                                   CollectionTag *)
  308. = {0x7014,collectionManagerTrap};
  309.  
  310.  
  311. pascal long CountTaggedCollectionItems (Collection, CollectionTag)
  312. = {0x7015,collectionManagerTrap};
  313.  
  314.  
  315. pascal OSErr GetTaggedCollectionItem (Collection,
  316.                                                   CollectionTag,
  317.                                                    long whichItem,
  318.                                                   long *itemSize,
  319.                                                    void *itemData)
  320. = {0x7016,collectionManagerTrap};
  321.  
  322.  
  323. pascal OSErr GetTaggedCollectionItemInfo (Collection,
  324.                                                            CollectionTag,
  325.                                                           long whichItem,
  326.                                                           long *id,
  327.                                                           long *index,
  328.                                                           long *itemSize,
  329.                                                           long *attributes)
  330. = {0x7017,collectionManagerTrap};
  331.  
  332.  
  333. pascal void PurgeCollection (Collection,
  334.                                       long whichAttributes,
  335.                                       long matchingAttributes)
  336. = {0x7018,collectionManagerTrap};
  337.  
  338.  
  339. pascal void PurgeCollectionTag (Collection, CollectionTag)
  340. = {0x7019,collectionManagerTrap};
  341.  
  342.  
  343. pascal void EmptyCollection (Collection)
  344. = {0x701A,collectionManagerTrap};
  345.  
  346.  
  347. pascal OSErr FlattenCollection (Collection,
  348.                                           CollectionFlattenProc,
  349.                                           void *refCon)
  350. = {0x701B,collectionManagerTrap};
  351.  
  352.  
  353. pascal OSErr FlattenPartialCollection (Collection,
  354.                                                       CollectionFlattenProc,
  355.                                                       void *refCon,
  356.                                                      long whichAttributes,
  357.                                                      long matchingAttributes)
  358. = {0x701C,collectionManagerTrap};
  359.  
  360.  
  361. pascal OSErr UnflattenCollection (Collection,
  362.                                              CollectionFlattenProc,
  363.                                              void *refCon)
  364. = {0x701D,collectionManagerTrap};
  365.  
  366.  
  367. pascal CollectionExceptionProc GetCollectionExceptionProc (Collection)
  368. = {0x701E,collectionManagerTrap};
  369.  
  370.  
  371. pascal void SetCollectionExceptionProc (Collection, CollectionExceptionProc)
  372. = {0x701F,collectionManagerTrap};
  373.  
  374.  
  375.  
  376. /*****************************************************************************************/
  377. /* Utility Routines for handle-based access...                                                          */
  378. /*****************************************************************************************/
  379.  
  380.  
  381.  
  382. pascal Collection GetNewCollection (short collectionID)
  383. = {0x7020,collectionManagerTrap};
  384.  
  385.  
  386. pascal OSErr AddCollectionItemHdl (Collection aCollection,
  387.                                                    CollectionTag tag,
  388.                                                    long id,
  389.                                                    Handle itemData)
  390. = {0x7021,collectionManagerTrap};
  391.  
  392.  
  393. pascal OSErr GetCollectionItemHdl (Collection aCollection,
  394.                                                  CollectionTag tag,
  395.                                                  long id,
  396.                                                    Handle itemData)
  397. = {0x7022,collectionManagerTrap};
  398.  
  399.                           
  400. pascal OSErr ReplaceIndexedCollectionItemHdl (Collection aCollection,
  401.                                                                    long index,
  402.                                                                Handle itemData)
  403. = {0x7023,collectionManagerTrap};
  404.  
  405.                                     
  406. pascal OSErr GetIndexedCollectionItemHdl (Collection aCollection,
  407.                                                              long index,
  408.                                                              Handle itemData)
  409. = {0x7024,collectionManagerTrap};
  410.  
  411.                           
  412. pascal OSErr FlattenCollectionToHdl (Collection aCollection, Handle flattened)
  413. = {0x7025,collectionManagerTrap};
  414.  
  415.  
  416. pascal OSErr UnflattenCollectionFromHdl (Collection aCollection, Handle flattened)
  417. = {0x7026,collectionManagerTrap};
  418.  
  419.  
  420. #ifdef __cplusplus
  421. }
  422. #endif
  423.  
  424.  
  425. #endif
  426.